Skip to content

docs(agentic): document get_pg_capabilities MCP tool (#135253)#133

Merged
gergesfikry-ottu merged 1 commit into
devfrom
task/135253-pg-capabilities-docs
Jul 13, 2026
Merged

docs(agentic): document get_pg_capabilities MCP tool (#135253)#133
gergesfikry-ottu merged 1 commit into
devfrom
task/135253-pg-capabilities-docs

Conversation

@gergesfikry-ottu

@gergesfikry-ottu gergesfikry-ottu commented Jul 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What & why

Documents the newly shipped get_pg_capabilities tool on the Ottu Core MCP server, which powers Agentic merchant onboarding — an agent uses it to discover which payment gateways and banks are available per country before configuring a merchant.

Ottu ticket: #135253.

This is an MCP tool, not a REST endpoint, so it is documented in a new "MCP Tools" developer section rather than under the auto-generated docs/developers/apis/* OpenAPI pages.

Pages added

Page Contents
developers/mcp-tools/index.mdx Ottu Core MCP server overview — Streamable HTTP /mcp/ connection, Bearer auth, per-tool permission model, and the shared { "error": ... } result envelope.
developers/mcp-tools/pg-capabilities.mdx Full get_pg_capabilities reference — permission, parameters, the three progressive-disclosure modes with real request/response examples, response schema (gateway profile / provider / wallet), enum reference tables, and error responses.

Also adds a Pattern-B "MCP Tools" category to developerSidebar in sidebars.ts (Overview + PG Capabilities), placed before Reference.

Faithful to source

Every example payload is taken verbatim from the core_backend tests (tests/test_contrib/test_mcp/test_mcp.py), so the docs match the tool's real output rather than a simplified spec. In particular:

  • Gateway and wallet name fields are bilingual objects ({ "en": …, "ar": … }), e.g. MPGS renders as Credit/Debit Card — not the raw code.
  • The supported-country order is the catalogue order: kw, ksa, om, bh, uae.
  • Permission gate is gateway.view_pgmid; error messages match the service exactly.
  • The write counterpart create_pg_config is intentionally not documented (held for #137821).

Human display names are used in prose (Apple Pay, National Bank of Kuwait); raw codes appear in the schema/enum tables. No internal implementation, credentials, or code is exposed.

Verification

  • npm run typecheck — passes.
  • npm run build — passes; the two new pages add no broken links or anchors (remaining build warnings are pre-existing on other pages).
  • Rendered locally via npm run serve + Playwright: overview and tool pages render correctly, the Mermaid workflow diagram renders with the correct single-accent styling, code blocks are syntax-highlighted, and the sidebar/anchor navigation works.

Base branch

Branched from dev and targets dev (the repo's integration branch → staging). Retarget to main if production-direct is preferred.

Please review — do not merge yet.

@gerges-ottu @claude
docs(agentic): document get_pg_capabilities MCP tool (#135253)
3ab28da 
Add an "MCP Tools" section to the developer docs covering the Ottu Core
MCP server and its first Agentic-onboarding tool, get_pg_capabilities:

- developers/mcp-tools/index.mdx — MCP server overview: Streamable HTTP
  connection, Bearer auth, per-tool permission model, error envelope.
- developers/mcp-tools/pg-capabilities.mdx — full tool reference: the
  three progressive-disclosure modes (countries / country / gateway)
  with source-faithful example payloads, response schema (gateway
  profile, provider, wallet), enum tables, and error responses.
- sidebars.ts — new "MCP Tools" category (Overview + PG Capabilities).

Examples and payloads are taken verbatim from the core_backend tests so
they match the tool's real output (bilingual gateway/wallet names,
catalogue country order, gateway.view_pgmid permission gate).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@gergesfikry-ottu
gergesfikry-ottu changed the base branch from main to dev July 13, 2026 14:17
@gergesfikry-ottu

gergesfikry-ottu commented Jul 13, 2026

Copy link
Copy Markdown
Contributor Author

@claude do code review

@claude

claude Bot commented Jul 13, 2026 •
edited
Loading

Copy link
Copy Markdown

Claude finished @gergesfikry-ottu's task in 3m 2s —— View job

Code Review

  • Gather context (diff, changed files)
  • Review docs/developers/mcp-tools/index.mdx
  • Review docs/developers/mcp-tools/pg-capabilities.mdx
  • Review sidebars.ts changes
  • Check against CLAUDE.md doc standards
  • Post final review

Nice addition — first documented MCP tool, and it's thorough. I verified every in-page anchor (#mode-1, #response-reference, #gateway-codes, #wallet-object, etc.) resolves to a real heading, cross-file links (/developers/mcp-tools/#connecting, /developers/payments/payment-methods, etc.) point at real docs, the mermaid block matches the repo's standard theme init exactly, and the base-URL code sample correctly uses OTTU_CONNECT_BASE_URL + <CodeBlock> per the root CLAUDE.md rule. Sidebar uses Pattern B (type: 'doc', one page per file) which is the right call for two substantial pages, consistent with checkout-sdk.

Note: I could not run npm run typecheck / npm run build in this sandboxed environment (command approval unavailable) — worth confirming those pass, especially since sidebars.ts id fields must match the doc front matter exactly.

One correctness/consistency issue and a couple of structural notes against docs/developers/CLAUDE.md:

1. docs/developers/mcp-tools/index.mdx:28-40 — standalone ## Authentication and ## Permissions H2 sections
docs/developers/CLAUDE.md explicitly says: "No standalone Authentication or Permissions sections — authentication is documented in getting-started/authentication.md." This page adds full ## Authentication and ## Permissions sections instead of just linking out.
That said, this may be a deliberate (and reasonable) exception: getting-started/authentication.md currently documents Basic Auth, API-Key, and Public Key — it never mentions Bearer token auth, which is what the MCP server actually requires. So this section isn't strictly duplicative today; it's filling a real gap. Two ways to resolve, your call:

  • Add "Bearer Token" as a fourth method in getting-started/authentication.md and shrink this section to a link + one-liner (matches the rule as written), or
  • Keep it inline here (since MCP auth is genuinely distinct) but note explicitly it's a new mechanism not covered on the authentication page, so a future reader of authentication.md doesn't miss it.
    Fix this →

2. docs/developers/mcp-tools/pg-capabilities.mdx — page structure diverges from the fixed template
The mandated section order is Overview → When to Use → Setup → Guide → API Reference → Best Practices → FAQ → What's Next?. This page instead has Overview → When to Use → Guide → Parameters → Usage modes → Response reference → Enum reference → Errors → FAQ → What's Next? — there's no ## API Reference H2 at all, and Parameters/Usage modes/Response reference/Enum reference/Errors aren't in the canonical list. This is understandable since there's no OpenAPI spec to embed via <ApiDocEmbed> for an MCP tool, and checkout-sdk/web.mdx shows precedent for reference-heavy pages departing from the feature-page template. Still, consider wrapping Parameters / Usage modes / Response reference / Enum reference / Errors under a single ## API Reference H2 (as H3s) so the page satisfies "API Reference always has an H2 heading" and stays scannable/consistent with other pages for readers jumping via TOC.

3. docs/developers/mcp-tools/pg-capabilities.mdx:36,53 — Guide subsections don't use the canonical names
CLAUDE.md specifies canonical ### subsections under Guide: Workflow, Live Demo, Step-by-Step, Use Cases. This page uses ### How it fits and ### Calling the tool instead. Minor/nit — the content itself is fine (mermaid flow + a walkthrough), but renaming to ### Workflow and ### Step-by-Step would match the convention other guide pages use.

Everything else — permission-gated error handling, the progressive-disclosure "3 modes" structure, the BNPL <details> example, the enum reference tables, and the FAQ (correctly using the <FAQ>/<FAQItem> component, matching invoices.mdx) — is well done and self-contained per the doc philosophy.
· Branch: task/135253-pg-capabilities-docs

@gergesfikry-ottu gergesfikry-ottu changed the title Task/135253 pg capabilities docs docs(agentic): document get_pg_capabilities MCP tool (#135253) Jul 13, 2026
@gergesfikry-ottu
gergesfikry-ottu merged commit 8ca013c into dev Jul 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@gergesfikry-ottu @gerges-ottu